feat(api): publish the deployment's OpenAPI schema - #358

Closes the gap the cloud UI's data-plane types name in their own docstring:

Hand-written rather than generated […] can drift from it silently. Generating them from the engine's OpenAPI is the correct fix and needs a pipeline that does not exist yet.

This is that pipeline. scripts/export_openapi.py builds the app in-process and asks FastAPI for the document — no server, no port. The app keeps openapi_url=None: refusing to serve the schema and refusing to publish it are different choices, and only the first is correct. The schema route sits outside the auth perimeter.

Four ways the document was wrong before it was right

All found by @codex.

Routes: 19 → 29 → 25. The middle number is the point — more is not better when the extras don't exist.

The guard got smaller, and that was the fix

Five instruments, each defeated:

1. Naming four routes I cared about — passed while the export omitted ten routes: the two operations endpoints, all seven /query/*, and /deployment. A missing route is invisible to a test that only asks about routes it remembered.
2. Freezing the whole route set — froze the phantom /connectors routes as readily as the real ones.
3. Comparing the two call sites by AST — caught connectors, but compared keyword spelling, which is not composition: auth=resolve_selfhost_api_auth(...) returns None for the open quickstart.
4. Enumerating evasions — **kwargs, second call, qualified call, aliased import, rebinding. codex produced two more that walked through.
5. Forbidding the class — every mention of build_api must be the callee. codex produced a sixth: import build_api as other plus a parameter default build_api=other, so the counted call is a decoy.

Static analysis cannot soundly answer "is there exactly one way to call this." That machinery is gone.

What remains is a frozen route set that is reviewed, not derived: the published surface cannot change without a person editing the list and saying why. That is what would have caught the phantom routes in the first place — not the machine, but the edit being visible in a diff.

Verified to fail:

Two tests I deleted without noticing

Mid-development, edits that rewrote a block of the test file removed a test each time. Nothing failed — a deleted test cannot fail — and the claim each supported stayed in my commit message describing a guarantee that no longer existed. codex caught the second.

There's now a count assertion. It's crude, and that's the point. It caught a miscount while this very change was being made.

A vacuous test I had to rewrite

My first auth test asserted 401 on a gated route — and passed with auto_error=True, because the perimeter raises first. The real risk was GET /healthz, which is perimeter-exempt: auto_error=True would have refused the container's liveness probe while every other route kept working.

Claims corrected along the way

Each of these was false when written, and each was caught in review rather than by me: that the compositions "cannot drift apart"; that the profile composes spend_lease; that HTTPBearer returns 403 (the pinned FastAPI returns 401); that /connectors would 404 on every deployment (a programmatic one can compose it); that this module is the "single place the HTTP surface is defined" (/healthz is still added by the profile, deliberately, and excluded from the schema); and that the docs page's every route is in the schema.

Docs (D66)

/docs/reference/api gains The machine-readable schema — where to get it, why the deployment doesn't serve it, how to generate a client, and the distinction review surfaced: capabilities nobody ships are absent, while capabilities you haven't configured are still listed, because no check on a published document can know your settings. /docs/project-status gains one bullet.

Site builds; 22 pages indexed.

The dotfile naming, recorded where the mistake was made

.env.example is published by GitHub as default.env.example — the API prefixes dotfile assets with default. Root cause of the fleet pin defect fixed in umc #419: four pins recorded the source name because whoever wrote the first read this workflow's file list rather than a release's asset list.

Checks

ruff, ruff format, pyright (0 errors, repo-wide); 430 surfaces tests pass; test inventory OK.

🤖 Generated with Claude Code

https://claude.ai/code/session_01UxXnThvjreGrY7c7CKM6TC

Contributor agreement

Signing on behalf of a legal entity (leave blank if accepting individually):

• I have read and agree to the RememberStack Contributor License Agreement v1.0.